Skip to main content

Usage

Endpoint for challenge list checking-adding-removing​

Endpoints related to adding-removing-checking a challenge listed address.

  • POST api.bitninja.io/api/addIpToGreylist
  • POST api.bitninja.io/api/deleteIpToGreylist
  • POST api.bitninja.io/api/checkIpOnGreylist

Common details shared between ALL endpoints​

They all require a JWT token for authorization. This will require the license key you can see at https://admin.bitninja.io/main

If we include a "result_mode=json" GET parameter, the result will be in json, that will look like this:

{ result: string }

PHP status code does NOT change even if validation fails or the action fails. It will always return 200.

Before every action carried out, the API will check if it is indeed a PUBLIC valid IPV4 address or not.

The limits are as follows:

  • challenge list additions/day: 6000.
  • challenge list removals /day: 1000.
tip

The API will NOT forward the request if the IP is on our global allow list (e.g. BitNinja's API IP addresses)

Common responses among all endpoints​

If the IP is invalid:

{result: "[1.2.3.4] is invalid"}

If the IP is private:

{result: "[1.2.3.4] is private"}

If you exceed a limit:

{result: "Sorry, but you have reached the maximum limit"}

Challenge list operations​

Checking​

POST api.bitninja.io/api/checkIpOnGreylist?result_mode=json (POST Parameters: IP)

Example Responses​

If the IP is NOT challenge listed:

{"result": "[1.2.3.4] is currently not on global challenge list"}

If the IP is on user-level challenge list:

{"result": "[1.2.3.4] is currently on your personal greylist"}

If it is challenge listed:

{"result": "[1.2.3.4] is on global greylist"}

Example CURL request​

curl --location --request POST 'https://api.bitninja.io/api/checkIpOnGreylist?result_mode=json' --header 'Authorization: Bearer <jwt_token>' --form 'ip="1.2.3.4"'

Adding​

POST api.bitninja.io/api/addIpToGreylist?result_mode=json (POST Parameters: IP)

Example Responses​

If the IP is already on user-level challenge list:

{"result": "[1.2.3.4] is already on your greylist"}

If the IP is on global challenge list:

{"result": "[1.2.3.4] is already on global greylist"}

If the IP was successfully added to the challenge list:

{"result": "[1.2.3.4] has been added to greylist"}

Example CURL request​

curl --location --request POST 'https://api.bitninja.io/api/addIpToGreylist?result_mode=json' --header 'Authorization: Bearer <jwt_token>' --form 'ip="1.2.3.4"'

Removing​

POST api.bitninja.io/api/deleteIpFromchallenge list?result_mode=json (POST Parameters: IP)

Example Responses​

If the IP is not on challenge list:

{"result": "[1.2.3.4] is not on greylist"}

If the IP has been successfully removed:

{"result": "[1.2.3.4] has been removed from greylist"}

Example CURL request​

curl --location --request POST 'https://api.bitninja.io/api/deleteIpFromGreylist?result_mode=json' --header 'Authorization: Bearer <jwt_token>' --form 'ip="1.2.3.4"'